/*
 * @(#)KeyPairGenerator.java	1.12 01/12/12
 *
 * 版权所有2002 Sun MicroSystems，Inc.保留所有权利。Sun专有/机密。使用受许可条款的约束。
 */
 
package java.security;

/**
 * KeyPairGenerator类用于生成公钥和私钥对。键生成器是使用<code>getInstance</code>工厂方法(返回给定类实例的静态方法)构造的。
 * 
 * 密钥生成是一个有时不适合算法独立性的领域。例如，可以生成指定密钥族参数(p、q和g)的DSA密钥对，而不能为RSA密钥对这样做。
 * 也就是说，这些参数适用于DSA，但不适用于RSA。
 * 
 * 因此，有两种方法可以生成密钥对：独立于算法的方式和特定于算法的方式。两者之间的唯一区别是对象的初始化。
 * 
 * 所有密钥对生成器都共享“强度”和随机性来源的概念。所有算法都普遍使用强度度量，尽管对不同的算法有不同的解释。
 * 此KeyPairGenerator类中的<a href>初始化</a>方法接受这两种通用共享类型的参数。
 * 
 * <p>由于在调用此独立于算法的<code>初始化</code>方法时未指定其他参数，因此算法参数、公共指数等所有其他值默认为标准值。
 * 
 * <P>
 * 有时希望使用算法特定的语义来初始化密钥对生成器对象。例如，您可能希望为给定的一组参数<code>p</code>、
 * <code>q</code>和<code>g</code>初始化DSA密钥生成器，或者为给定的公共指数初始化RSA密钥生成器。
 * 
 * <P>
 * 这是通过特定于算法的标准接口完成的。不是调用与算法无关的KeyPairGenerator<code>初始化</code>方法，
 * 而是将密钥对生成器强制转换为特定于算法的接口，以便可以调用其专用的参数初始化方法之一。
 * DSAKeyPairGenerator接口就是一个例子(来自<code>java.security.interface</code>)。
 * 
 * 有关详细信息和示例，请参阅《Java加密体系结构API规范与参考》中的<a href>KeyPairGenerator类。
 * 
 * @see java.security.interfaces.DSAKeyPairGenerator
 */
public abstract class KeyPairGenerator {

    private String algorithm;

    /**
     * Creates a KeyPairGenerator object for the specified algorithm.
     *
     * @param algorithm 算法的标准字符串名称。有关标准算法名称的信息，请参阅<a href>Java加密体系结构API规范和参考中的附录A。
     */
    protected KeyPairGenerator(String algorithm) {
	this.algorithm = algorithm;
    }
    
    /**
     * 返回此密钥生成器的算法的标准名称。
     * “../Guide/Security/Cryptospec.html#Appa”>Java加密体系结构API规范&；参考</a>，了解有关标准算法名称的信息。
     * 
     * @return the standard string name of the algorithm. 
   */
    public String getAlgorithm() {
	return algorithm;
    }

    /**
     * 生成一个KeyPairGenerator对象，该对象在环境中可用时实现所请求的算法。
     *
     * @param algorithm 算法的标准字符串名称。有关标准算法名称的信息，请参阅<a href>Java加密体系结构API规范和参考中的附录A。
     *
     * @return the new KeyPairGenerator object.
     *
     * @exception NoSuchAlgorithmException if the algorithm is
     * not available in the environment.  
     */
    public static KeyPairGenerator getInstance(String algorithm)
    throws NoSuchAlgorithmException {
	try {
	    return (KeyPairGenerator)Security.getImpl(algorithm, 
						      "KeyPairGenerator",
						      null);
	} catch(NoSuchProviderException e) {
	    throw new InternalError("please send a bug report via " + 
				    System.getProperty("java.vendor.url.bug"));
	}
    }

    /** 
     * 生成一个KeyPairGenerator对象，该对象实现由指定提供程序提供的指定算法(如果该提供程序提供了这样的算法)。
     *
     * @param algorithm 算法的标准字符串名称。有关标准算法名称的信息，请参阅<a href>Java加密体系结构API规范和参考中的附录A。
     *
     * @param provider the string name of the provider.
     *
     * @return the new KeyPairGenerator object.
     *
     * @exception NoSuchAlgorithmException if the algorithm is
     * not available from the provider.
     *
     * @exception NoSuchProviderException if the provider is not
     * available in the environment. 
     * 
     * @see Provider 
     */
    public static KeyPairGenerator getInstance(String algorithm,
					       String provider) 
    throws NoSuchAlgorithmException, NoSuchProviderException {	
	return (KeyPairGenerator)Security.getImpl(algorithm, 
						  "KeyPairGenerator",
						  provider);
    }

    /**
     * Initializes the key pair generator for a certain strength.
     *
     * @param strength 钥匙的力量。这是特定于算法的度量，例如模长。
     *
     * @param random the source of randomness for this generator.
     */
    public abstract void initialize(int strength, SecureRandom random);

    /**
     * 使用系统提供的随机性源将密钥对生成器初始化为特定强度。
     *
     * @param strength 钥匙的力量。这是特定于算法的度量，例如模长。
     */
    public void initialize(int strength) {
	initialize(strength, new SecureRandom());
    }


    /**
     * 生成密钥对。除非使用KeyPairGenerator接口调用初始化方法，否则将使用特定于算法的默认值。
     * 这将在每次调用它时生成一个新的密钥对。
     */
    public abstract KeyPair generateKeyPair();
}
